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MATH LIBRARY ERRATA 


If you use the LightspeedC library "math", you may encounter a problem with the functions exp(), 
pow(), tan(), sinh(), or cosh(). 


The problem is that the Standard Apple Numerics Environment (SANE) does not reset the error 
flags when it is called. If the SANE overflow error flag happens to be set for any reason, calls to 
any of exp(), pow(), and sinh() will refer to this flag and also return an error when 
there is no error. A call such as log(0.0) is one which sets the SANE overflow error flag and 
creates this situation. A similar condition is possible for the tangent function tan(), which uses the 
SANE invalid operand flag. cosh() is affected because it uses the exp() function. 


CORRECTION 


The following describes changes to be made to the math.c file, the source module for the library 
called "math". Using LightspeedC, create a new project that contains only the file "math.c", which 
is included on the library disk "LS2.Libraries". 


Edit the C functions exp(), pow(), and sinh() to add the following statement as the first 
statement of each of these functions: 


SANEglobalenv.overflow = 0; 
A similar situation exists for the tan() function. Add the following statement as the first 
statement of the tan() function: 

SANEglobalenv.invalid = 0; 
The source file math.c is now corrected. Save it, compile it, and then select Build Library from 


the Project menu. Name the library "math" (or something else if you prefer such as "new math"). 
You should now use this library in place of the original math library. 
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1 
Introduction 


Welcome to the second release of LightspeedC, version 2.01. Many new features have been added since 
the original release, so please read this document carefully to familiarize yourself with them. This 
release also fixes all known bugs. 


LightspeedC has grown as a result of the enhancements in this release. Approximately 28K more disk 
space is used. There is approximately 11K less available memory in the LightspeedC development 
environment. (There is, however, an option to obtain more memory at the expense of longer compile 
times. Read about the More Memory option on page 16 of this supplement.) 


This supplement documents features which are new to this LightspeedC release. The original release of 
LightspeedC, version 1.02, was accompanied by a short supplement documenting features of the 
product that, for one reason or another, were not adequately described in the User's Manual. That 
material has been incorporated into the present supplement. To allow you to identify the older material, 


it is indicated by the marker immediately prior to the section to which it applies. Information so 
marked is not new to this release, but it does not appear in the User's Manual. 


. Note: We are no longer shipping a System Folder with LightspeedC. Use the System, Finder, and 
Font/DA Mover supplied with your Macintosh. 


What to Read First 


This is a large document, so we'd like to call your attention to certain portions that we especially hope 
you won't miss. 


If you have been using the original release of LightspeedC, be sure to read "A Note on Converting Old 
Projects", below. If you've ever dreamed of an even faster LightspeedC, read the chapter "Running 
with Switcher". 


If you are new to LightspeedC, the section "hello, world' in LightspeedC", on page 47, can get you 
started in a hurry. You may also find the section "Recommended Disk Layouts", on page 46, helpful. 


If you are using the Hierarchical File System (HFS), be sure to read the section "Handling of HFS" on 
page 3. i 


Everyone should be aware of the section "Using a Separate Resource File", on page 4. This section 
replaces Chapter 8 of the User's Manual. An appendix to this supplement contains other errata to the 
manual. 
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A Note on Converting Old Projects 


This release (version 2.01) of LightspeedC uses a slightly different project document format than the 
previous release (version 1.02). When you open an old project, LightspeedC will automatically convert 
it to the new format, after asking you for confirmation. 


If you bring up the Make... (38M) dialog after the conversion, you will see that all the source files are 
checked, indicating they need to be recompiled. Actually, the code generated the last time each source 
file was compiled is still intact. However, include-file information stored in the project for use by the 
Auto-Make facility is lost as a result of the conversion process. To regenerate this information, all 
source files must be recompiled. If the project is one which you obtained from a third party, you might 
not have all the sources! In this case, simply use Make... (98M) to uncheck the files that can't be 
recompiled. 


If your project uses libraries, such as MacTraps or stdio, that have changed with this release, they are 
not automatically reloaded. Reload them manually or bring up the Make... (8M) dialog and select 
Use Disk, then OK. 


Projects created by LightspeedC version 1.02 can be used as libraries (i.e. using Add...) without 
requiring conversion. However, LightspeedC version 1.02 cannot open a project created (or 
converted) by LightspeedC version 2.01; the message "unknown error, ID--192"is generated. 


A Note About Customer Support 


A large portion of our technical support calls regard a few common problems. On page 48 of this 
supplement is a section called "Some Common Problems" describing these problems and their solutions. 
Before calling our customer support number, please check this section for possible solutions to your 
problem. 


LightspeedC is a Trademark of THINK Technologies, Inc. 

Consulair and MacC are Trademarks of Consulair Corporation. 

HyperDrive is a Trademark of General Computer Corporation. 

UNIX is a Trademark of AT&T Bell Laboratories Inc. 

Macintosh is a Trademark of McIntosh Laboratory, Inc. and is used by Apple Computer, Inc. with its express permission. 
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2 


The LightspeedC Environment 


Handling of HFS 


LightspeedC treats the entire subtree rooted at the project directory as though it were one large "flat" 
folder. The project directory is defined as the directory containing the project document, but all files in 
subdirectories, sub-subdirectories, etc., of the project directory are treated as if their files were in the 
project directory itself. Similarly, files are treated as if they are in the LightspeedC directory if they are 
in the directory containing the LightspeedC application, or in any subdirectory, sub-subdirectory, etc., 
of that directory. 


This method of handling folders allows you to organize your files into subdirectories as you see fit, 
without having to use absolute (or even relative) pathnames to refer to them. LightspeedC automatically 
searches the project and LightspeedC trees as necessary to find a file. However, there are some 
consequences of this scheme that you need to be aware of: 


Just as you cannot have two files with the same name in different "flat" folders on an 
MFS volume, you should not have duplicate file names in different subdirectories of 
the project (or LightspeedC) tree. If you do, LightspeedC will get confused about 
which of several files with the same name it should use. This will not lead to any 
explicit errors, but the "wrong" file may, in fact, used. (Be aware that Save As... 
copies files, rather than merely moving them, and so if you use Save As... to move 
a file from one folder to another without changing its name, be sure to delete the 
original one.) 


If you want to "shield" a directory from the tree search, enclose its name in 
parentheses. For example, you might have a subdirectory of the project directory 
named (Backups). The files in this directory (and in any subdirectories, sub- 
subdirectories, etc.) will not be treated as part of the project tree, and may have names 
which are the same as files elsewhere in the tree. 


Its OK to have the same file name in both the project and LightspeedC trees: the 
conflict is resolved deterministically by search order. 


It is unwise to place a project directory within the LightspeedC tree, since it will be 

searched whenever the LightspeedC tree is searched, even when you are working on a 

different project. Some people like to organize all their LightspeedC work together, so 

they make each project directory a subdirectory of the LightspeedC directory. This is 

not a good idea under HFS. If you want to organize your work this way, put the 

AA directory and your project directories together in the same master 
ectory. 


Searching the trees can be time-consuming, but LightspeedC remembers where it last 
found each file and looks there first the next time. So, when you are initially building 
a project, or if you've moved files around within the tree, compilations might be 
slower than usual at first. Don't worry. Once LightspeedC has learned where all your 
files are, it will speed up again. 
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Note that the tree search performed to achieve this emulation of "flat" folders is different from, and 
independent of, the search which is performed by the preprocessor to find include-files. As always, the 
search order for include-files (if not specified by absolute pathname) is: (1) referencing directory (that 
is, the directory containing the file in which the #include statement appears), (2) project directory, 
(3) LightspeedC directory. For simple filenames (i.e. foo.h, not :dir:foo.h), the entire project and 
LightspeedC trees are potentially searched; if the referencing directory falls within the LightspeedC 
tree, the LightspeedC tree is searched before the project tree. 


A file may be moved freely within a tree: the tree search will automatically find it. If you want to move 
a file from the project tree to the LightspeedC tree, or vice versa, select Use Disk (in the Make... 
(36M) dialog) to get LightspeedC to notice the change. 


Your project may contain files which are outside either tree; they are known by absolute pathname. Use 
Get Info (ÆTI) to find out whether a file lives in the project tree, the LightspeedC tree, or outside. If 
you want to move a file known by absolute pathname into one of the trees, you will have to either 
Remove it and Add it back to get LightspeedC to notice the change, or open the file and Save As... 
a file in the desired tree. 


The new scheme is designed to allow projects to be easily moved from one machine to another. When 
you move a project to a new machine, it is strongly recommended that you select Use Disk to let 
LightspeedC find all the files. Files need not be in the "same" places on the two machines as long as 
they are within the project or LightspeedC trees. Files outside either tree must have the same absolute 
pathname on the two machines. | 


The separate resource file associated with each project (projectName.rsrc) must appear in the actual 
project directory, not in any subdirectory: it is not searched for. Similarly, the DAShell application 
must reside in the actual LightspeedC directory. 


"Use Disk" Enhancements 


Use Disk (in the Make... (38M) dialog) now displays its progress. You can abort it by typing 
46. (command-period), although the next Use Disk will start again at the beginning. 


If a source file or library is not found by Use Disk, its make status (i.e. whether it is checked in the 
Make... box) is unchanged. As before, however, if a source file is found but one of the files it 
includes is not found, the source file is marked as needing to be made (i.e. it is checked). 


Using a Separate Resource File 


Chapter 8 and page 3-13 (paragraph 3) of the LightspeedC User's Manual describe how to access 
resources from a separate resource file during development, then later merge the resources into the file 
built by Build Application.... Since the User's Manual went to press, LightspeedC has been 
enhanced and this process is now largely automatic. 


You still need to place any resources your program needs in a resource file; you can use RMaker, 
ResEdit, or any other appropriate method to create this file. But, provided you obey a simple naming 
convention, your resource file will automatically be opened when you run your application under 
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LightspeedC, and your resources will automatically be copied into the stand-alone file you eventually 
. ouild. 


You should give your resource file a name consisting of the name of the project with the extension 
.rsrc appended. If your project document is titled MyProg, your resource file should be titled 
MyProg.rsrc. The .rsrc extension does not replace any existing extension: if your project document 
is named MyProg.proj, your resource file should be named MyProg.proj.rsrc. Furthermore, the 
resource file must be kept on the same volume—and under the Hierarchical File System (HFS), in the 
same folder—as the project document. 


When you issue the Run command from LightspeedC's Project menu, your resource file will be 
opened automatically. You do not need to call OpenResFile from your program as described in 
Chapter 8. 


When you issue one of the Build Application..., Build Desk Accessory..., Build Device 
Driver..., or Build Code Resource... commands, resources from your resource file will 
automatically be incorporated into the application, driver, or code resource file being built. You do not 
need to use an RMaker script or any other method to merge resource files as described in Chapter 8. 


Setting the Application Creator 


Set the creator by filling in the Creator field in the Set Project Type... dialog. If the field is set to 
???? (the default), and the application being built will overwrite an existing application, then the 
. zreator is left unchanged. 


More "Check Link" Information 


The Check Link command indicates, in the Link Errors window, the files in which each undefined 
symbol is referenced and in which each multiply defined symbol is defined. 


When the Link Errors window comes up as the result of an attempt to Run (ÆR) or Build..., this 
additional information is not displayed. Some disk activity is required to compute the information, so it 
is only displayed when you specifically request Check Link. 


Typing in the Project Window 


You can select a file in the project window by typing the first portion of its name, much as you can in 
Standard File. Since the files in the project window are not all in alphabetical order, the selected file is 
simply the first file in the project which matches the characters typed so far. If no file matches, any 
selected file is deselected (this is different from Standard File). There is a timeout feature just as in 
Standard File; if sufficient time elapses between keystrokes, a new sequence is begun. The tab key can 
be used to cycle among multiple files that match the characters typed so far. 


The up-arrow and down-arrow cursor keys may also be used to move around in the project window. 
— The return and enter keys may be used to open the selected file, just like double-clicking. 
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"Remove Objects". Command 

This command, found in the Project menu, reverses the effects of all previous compilations and 
loading of libraries. The project document is "dehydrated"; it can be "reconstituted" by recompiling all 
source files and reloading all libraries. 


Use this command when you need to make the project document as small as possible, e.g. for archiving 
or for transmitting to someone else. 


Options Dialog 
The Options menu is gone; in its place is a dialog displayed by selecting Options... from the Edit 


menu. There are several new options—Check Pointer Types, Require Prototypes, and More 
Memory—which are described in the relevant sections in this document. 


"More Memory" Option 

This option is initially unchecked. When checked, LightspeedC tries to find more memory during 
compilation by discarding certain data structures. This incurs some additional disk activity, since (1) 
the data structures will need to be read back in when compilation is complete, and (2) if they are "dirty", 
the data structures must be written out prior to compilation in case the compiler runs out of memory. 


Leave this option unchecked unless you are developing a large project on a small machine which keeps 
running out of memory. 


Opening a Source File from the Finder 
If you double-click on a LightspeedC source file document in the Finder, LightspeedC will, as usual, 


launch and prompt you for a project document. Once you have selected a project, the source file will be 
opened up automatically. 


RelConv Enhancements 

RelConv accepts a script file containing a list of Rel files, one per line. The script file must be a text 
file with an extension of .RCV. If relative pathnames appear in the script file, they are interpreted 
relative to the directory containing the script file. 


RelConv now has an Options menu. There is only one option, requesting RelConv to delete each 
.Rel file after converting it. 


RelConv now has a File menu with Transfer... and Quit selections. 


RelConv can convert .Rel files generated by MDS 1.0, MDS 2.0, and Consulair's Mac C compiler. 
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3 
The Editor 


Windows Menu 


The Windows menu has three sections, separated by dotted lines. The first section has five 
commands: Clean Up, Zoom (4/), Full Titles, Close All, and Save All. The second section 
has an entry for the project window and one for each Untitled window. The third section has an entry 
for each file open in an edit window, in alphabetical order. 


Clean Up 

The edit windows are neatly re-stacked, as though they were freshly opened. The rearmost window is 
assigned the first slot, as though it was the first window opened, the next-rearmost window is assigned 
the second slot, etc. The front-to-back order of the windows is not changed. 


Zoom (36/) 

The front window is zoomed to full screen; if it is already at full screen, it is restored to its previous 
position and size. This is equivalent to clicking the window's zoom box in the upper right corner of the 
window. Note that this feature does not require 128K ROMs. 


Full Titles 
— This is a checkable item; it is initially unchecked. When checked, the title of each edit window indicates 
the volume name and directory name as well as the file name. 


Close All 
All edit windows are closed. If the Confirm Saves option is checked, you are asked whether you 
want to save each modified window, otherwise windows are automatically saved. - 


Save All 
All modified edit windows are saved. No confirmation is requested. 


Project window (360) (Command-zero, not Command-oh) 
The project window is brought to the front. (The menu item will be the name of the project, not the 
literal words "Project window".) 


Titled and Untitled edit windows (381-9) 

The selected window is brought to the front. The number reflects the "slot number", i.e. the initial 
position of the window. (The first created window occupies slot #1, and slots 446-10 occupy the same 
screen positions as slots #1-5, etc. Slots vacated by closed windows are.reused at the next 
opportunity.) The number of windows is limited only by available memory, but only windows in the 
first € slots have a d-key equivalent. A diamond (©) appears next to windows which have been 
modified. 
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Find Definition of Symbol 


If the Option (or 36) key is depressed while double-clicking in an edit window to select a word, 
LightspeedC opens the file in which the selected symbol is defined and searches for its first occurrence 
in that file. This will often be the definition of the symbol, but not always. The search string is set to 
the symbol, so Find Again (88A) can be used. 


This is not a pure text operation but rather is based on information maintained by the compiler. The file 
defining the symbol must have been compiled for the editor to be able to find it. Furthermore, only 
global (non-stat ic) functions and variables can be found in this way, since no information is retained 
about other names after compilation. 


If the symbol is multiply defined, one of the files defining it is selected arbitrarily. 


Pop-up Include-File Menu 


Option- (or 36-) clicking in the title bar of an edit window brings up a menu of include-file names. The 
window must contain a .c file; the menu will display the names of files included by the .c file the last 
time it was compiled in the currently open project. Choosing a file from the menu opens that file or 
brings its window forward. 


This is not a text operation; it is based on information known as of the last compilation. The editor 
doesn't know about include statements. To open an include-file added since the last compilation, 
select its name and use Open Selection (D). 


If a source file has a lot of include-files, the menu could be too long to fit on the screen; it will be 
truncated. If you are running System 3.2, the menu will automatically scroll when you position the 
mouse at the bottom of the menu. (If you are running System 2.0 and prefer not to upgrade to 3.2, you 
can use ResEdit to copy the MDEF 0 resource from the 3.2 System file into your System file; this gives 
you scrolling menus, even on 64K ROMs!) 


Undo 


The last edit operation may be reversed by selecting Undo (9Z) from the Edit menu. The name of 
the command in the menu changes appropriately (e.g. Undo Paste). Once undone, the command 
changes to Redo (Redo Paste, etc.). The change may be restored by selecting the command again. 
If there is nothing to undo, the command is dimmed. If the currently available undo operation applies 
to a window which is not frontmost, the name of the command in the menu indicates that there is 
something to undo, but the command is dimmed. 


Replace All and Revert cannot be undone. Set Font... and Set Tabs... also cannot be undone; 
however, since they do not modify the text, they are not considered edit operations and therefore they 
do not affect the current undo status. 
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_ "Balance" Command 


Balance (38B) extends the current selection in both directions until it encloses the smallest surrounding 
balanced text enclosed in parentheses (), brackets [], or braces {}. Successive invocations select 
larger sequences of text. 


Try this: Start at the beginning of a file and search for the first left brace {. Then use Balance (36B ) 
and Find Again (88A) repeatedly until you get to the end of the file. This is a quick way to check 
whether all your function definitions are properly balanced. 


Balance is a purely textual operation. It does not know about comments or strings. 


Keyboard Usage 


Cursor Key Support 


In the editor, arrows move the insertion point up, down, left, right. Option-arrows move the insertion 
point to the beginning of file, end of file, beginning of line, end of line. Shift-arrows and shift-option- 
arrows extend the current selection. 


Note: Unfortunately, it is not possible to distinguish between shift-arrows and the +, *, /, and = keys 
on the numeric keypad of the Macintosh Plus keyboard. For example, when you type a + on the 
keypad, it will be treated as a shift-left-arrow. This is unavoidable because of the hardware design. 


"Enter" Key 


As before, the "Enter" key brings the start of the selection onto the screen. If the start of the selection is 
already visible, "Enter" now makes the end of the selection visible. You can thus toggle between the 
two ends of the current selection. This is particularly useful after using the Balance (38B) command. 


"Clear" Key 


The "Clear" key on the keypad or Macintosh Plus keyboard is equivalent to the Clear command in the 
Edit menu. 


Default Font/Tab Settings 


By default, an Untitled window created by the New (38N) command appears in Monaco-9 with tabs 
set every 4 spaces. You can change this by using ResEdit to modify the CNFG 0 resource in the 
LightspeedC application. This resource consists of four two-byte words. The first word stores option 
settings, and should be changed only by the Options... command. The second, third, and fourth 
— specify the font number, font size, and tab width, respectively, used for newly created Untitled 
— windows. 
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Search and Replace 


"Enter Selection" Command 


The Enter Selection ($E) command, in the Search menu, sets the search string to the current 
selection, clearing Grep and Multi-File Search. You can then use Find Again (8A) to begin 
searching, or Find... (36F) to set search options. 


Disabling Multi-File Search 
Entering a new search string cancels a pending multi-file search. 


To enter a new search string without cancelling a pending multi-file search, bring up the Find... (38F) 
dialog, click Multi-File Search, click OK in the multi-file selection box, and then enter the desired 
search string. 


To cancel a pending multi-file search without entering a new search string, option- (or 3£-) click on the 
Multi-File Search checkbox. 


a&Tab and #Return 


The tab and return characters may be entered directly in the Find... dialog box by typing them with the 
Command (36) key held down. 


Grep 


ing: What follows in the section describing Grep mode is not for the faint- 
hearted. If you are not already familiar with Grep, it is strongly recommended that 
you experiment with this feature before attempting to use it on your files. It is both 
powerful and tricky, and is frequently useful, but can lead to unexpected and 
unfortunate results if not used correctly. 


The grep mode of operation for the LightspeedC Search command is a powerful tool. At the expense 
of being somewhat slower than the normal string-search mode, the grep mode allows you to search for 
one of a set of many strings instead of a particular string. As a simple example, you can search for any 
occurrence of an identifier beginning with the letter P, such as Ptr or Point, instead of one specific 
string. This is described later in this section. 


Grep is a standard utility on Unix™ systems that is used to search through one or more files for 
occurrences of strings that match a given pattern and print the lines containing those strings. Most 
Unix-based editors also have this pattern-search capability, most notably ed and ex derivatives such 
as vi. 


LightspeedC Release 2.01 Supplement Page 10 
Copyright O 1986 THINK Technologies, Inc. 


A pattern is a string of characters that, in turn, describes a set of strings of characters. We say that a 

_.tring is matched by a pattern if it is a member of the set described by the pattern. When you invoke 
one of the Search menu selections in grep mode, LightspeedC looks for and selects the next 
occurrence of a string that matches that pattern. 


The kinds of patterns we describe below are sometimes referred to as regular expressions, but they 
really are not. True regular expressions are capable of describing sets of strings that these patterns 
cannot. By convention, the expressive power of these patterns is limited somewhat so that pattern 
searching can be implemented more efficiently. 


We begin by describing the simplest kinds of patterns, those that match a single character. Afterwards, 
we will describe how to construct more complex patterns. Keep in mind that pattern matching is done 
on a line-by-line basis. Therefore, a pattern will never match a string that spans line boundaries 
because the character that separates lines (carriage return, the ASCII CR) can never be matched. 


e Any character, with the exceptions noted below, is a pattern that matches itself. So, 
for example, the pattern 2 will match an occurrence of a character 2 in the text being 
searched. Note that if you have checked Ignore Case in the Find... dialog box any 
letter will match both its upper- and lower-case equivalent. Thus, either a or A will 
match both a and A. 


e The character . is a pattern that will match any character. 


e The character \ followed by any character is a pattern that matches that character, 
except for ( ) < >oroneof the digits 1-9. Thusa . can be matched with V. and 
a \ can be matched with YA. 


e A String of characters s surrounded by a [ and a ] is a pattern [s] that matches any 
one of the characters in the string s. The pattern [^s] matches any character that is 
not in the string s. If a string of three characters in the form a-b occurs in s, this 
represents all of the characters from a to b inclusive. All other characters in s are 
taken literally, and the only way to include the character ] in s is to make it the very 
first character. Likewise, the only way to include the character - in s is to have it 
either at the very beginning or the very end of s. Note that the Ignore Case option 
has no effect between brackets. As an example, the pattern [A-Za-z0-9] matches 
any alphanumeric character. The pattern [^!--] matches any character that is not 
one of the standard, printable ASCII characters. 


Since we want to be able to match strings, not just individual characters, we need to have patterns that 
are able to match consecutive sequences of characters. One way of doing this is to append a * to the 
end of one of the above patterns. 


e A pattern x followed by a * is a pattern x* that matches zero or more consecutive 
occurrences of characters matched by x. For example, the pattern @* will match a 
string containing any number of at-signs. If a string to be matched does not begin 
with an at-sign, or contains no at-signs at all, then we say that the pattern matches the 
empty string at the beginning of the string to be matched. The utility of this will be 
demonstrated further on. 
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Patterns may be concatenated to form more complex patterns: 


A pattern x followed by a pattern y forms a pattern xy that matches any string ab, 
where a can be matched by x and b can be matched by y. 


Of course, the compound pattern xy can be concatenated with another pattern z, 
forming the pattern xyz. 


As an example of a pattern that uses the capabilities described so far, consider the pattern (.*) . 
This pattern will match any string that is enclosed in parentheses. This includes the string () , since the 
sub-pattern . * will match the empty string between the ( and the ) . But what about the string ( () )? 


Since the sub-pattern 


. * will match any number of occurrences of all characters, won't the pattern 


match just the (() and not the very last ) ? The answer is any sub-pattern of the form x* in a pattern 
x*y will match the largest number of occurrences of whatever x matches that still allows a match to 
y. Therefore, in matching (()) against the pattern ( . *) , only the inner pair of parentheses will be 
matched by the sub-pattern . *. 


We now have the ability to form patterns that are composed of sub-patterns, and will find it useful to 


remember sub-strings matched by sub-patterns and to be able to match against those sub-strings. 


A pattern surrounded by \ ( and \) is a pattern that matches whatever the sub-pattern 
matches. 


A \ followed by n, where n is one of the digits 1-9, is a pattern that matches 
whatever was matched by the sub-pattern beginning with the nth occurrence of \ ( . 
A pattern V may be followed by an *, and forms a pattern \n* that matches zero or 
more occurrences of whatever \n matches. 


Note that, in the pattern \ (a. bN) V1, the sub-pattern \1 does not imply a re- 
application of the sub-pattern a.b . If N (a. bX) was matched with the string axb, 
then the sub-pattern \1 would try to match the literal string axb against the remainder 
of the search string. Therefore, the pattern \ (a.b\) \1 will match axbaxb, but will 
not match axbazb. 


We finally will find it useful to be able to constrain patterns to match only if certain conditions in the 
context outside the string matched are met. 


A pattern surrounded by \< and V» is a pattern that matches whatever is matched by 
the sub-pattern, provided that the first and last characters of the matched string can be 
matched by [A-Za-z0-9 ] and that the characters immediately surrounding the 
matched string cannot be matched by [A-Za-z0-9 ]. 


This is used to match any string that matches the sub-pattern only if the matched string 
begins and ends on a word boundary. Note that if you have checked Match Words 
in the Find... dialog box, then the entire pattern you enter will be treated as though it 
were surrounded by \< and \>. 


A pattern x that is preceded by a ^ forms a pattern ^x . If the pattern ^x is not 
preceded by any other pattern, it matches whatever x matches as long as the first 
character matched by x occurs at the beginning of a line. If the pattern ^x is preceded 
by another pattern, then the ^ is taken literally. 
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e A pattern x that is followed by a $ forms a pattern x$. If the pattern x$ is not 
followed by any other pattern, it matches whatever x matches as long as the last 
character matched by x occurs at the end of a line. If the pattern x$ is followed by 
another pattern, then the $ is taken literally. 


These last two items constrain pattern matches to begin or end at line boundaries, and can be combined 
to constrain a pattern to match an entire line only. 


We mentioned at the beginning of this section that you could use grep mode to search for any identifier 
beginning with the letter P . You can do this with the pattern \< [Pp] [A-Za-z0-9 ]*\> . Note 
that, if you had checked Ignore Case in the Find... dialog box, then the patterns 
\<P [A-Za-z0-9 ]*\>and \<p[A-Za-z0-9 ]*\> would match the same strings. Also, if you 
had checked Word Match in the Find... dialog box, then any of these patterns with the \< and \> 
removed would match the same strings. 


In grep mode, not only is searching different from the normal mode of operation, but replacement is 
also. In a replacement string (as specified in the Replace with: portion of the Find... dialog box), 
the following substitutions are made before any text replacement occurs: 


e Each occurrence of the character & is replaced with whatever was matched by the 
entire pattern. 


e Each occurrence of a string of the form \n, where n is one of the digits 1-9, is 
replaced by whatever was matched by the sub-pattern beginning with the nth 
occurrence of \ (. 


e Each occurrence of a string of the form \x, where x is a character other than one of 
the digits 1-9, is replaced by x. 


This allows you to not only be able to search for a string satisfying a complex set of conditions, but 
also to be able to do a subsequent replacement that varies depending on the string that is matched. 


As an example, suppose that you have written a program that is to become a Macintosh application 
(i.e., it uses the Macintosh Toolbox instead of stdio for the user interface). Suppose also that you 
have discovered that you have forgotten to put a \p at the beginning of your string constants, so that 
your program will pass C strings instead of Pascal strings to the Toolbox (which expects Pascal strings 
as arguments). You can easily change all your C strings to Pascal strings by specifying 


" ( ji *X) " 
as the search pattern and 
" x NDA T " 


as the replacement string. 
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4 
The Compiler 


Code Generation 


Register Variables 


There are actually more register variables available than the LightspeedC User's Manual indicates. In 
fact, five (5) data registers and three (3) address registers are available to hold register variables. (Of 
course, any registers not used to hold register variables are available to hold temporary results during 
expression evaluation.) In a desk accessory, device driver or code resource, address register A4 is 
reserved to point to the global data area, so only two (2) address register variables are available. 


Short Branches 


The code generator produces short branches when it can. Backward branches are always generated 
_ correctly and optimally. Forward branches are always generated correctly, but occasionally not 
optimally: some long forward branches are generated which could be short. (Nobody's perfect.) 


On average, this optimization seems to be good for about 4% to 8% reduction in code size. 


Stack Frames and the "Macsbug Symbols" Option 


Previously, setting the Macsbug Symbols option forced the compiler to generate MC68000 LINK 
and UNLK instructions to create a stack frame for each function. This is because Macsbug looks for 
these instructions to find functions whose names are embedded in the code. When the Macsbug 
Symbols option was unchecked, only functions which had arguments, non-register local variables, or 
compiler-generated temporaries were given a stack frame. 


Now, the setting of the Macsbug Symbols option has no effect on the code generated for each 
function. A stack frame is never generated solely for Macsbug's benefit, and function names are 
embedded in the code only for functions with stack frames. (You can force a function to have a stack 
frame by declaring a dummy argument or non-register local variable.) 


Note that, as before, the Profile option forces a stack frame, even if none would otherwise have been 
needed. Some assembly language routines (e.g. those in stringsasm.c) are not expecting stack frames 
and should not be compiled with the Profile option. 
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Floating to Integer Conversions 


Floating-point values converted to arithmetic types are now truncated, rather than rounded, to integral 
values. 


Function Prototypes 


This is an ANSI extension to C. A function prototype is a function declaration with additional 
information describing the arguments. For example: 


extern int strcpy(char *dest, char *source); 
extern int printi(char S; ...); 


Argument identifiers are optional and are ignored if supplied. Functions with variable numbers of 
arguments can be specified by using ... as the last argument; no information is provided about the 
additional arguments beyond that they are allowed. 


A function declaration with no argument information, e.g. 


extern long foo(); 


Is not a prototype and supplies no information about the arguments. It only declares the return type. 
To give a prototype stating that the function takes no arguments, use 


extern long foo(void); 
(This is a special case and does not mean that the function takes a void argument!) 


If a prototype is in effect when a function is called, the actual arguments are checked against the 
prototype. Unless the prototype ends in . . ., the number of arguments must match exactly. The types 
of the arguments must be assignment-compatible (the state of the Check Pointer Types option is 
honored). Appropriate conversions are applied to arithmetic (integral and floating-point) values. 
Additional arguments allowed by the . . . are not checked or converted. 


If a prototype is in effect when a function is defined, the definition is checked against the prototype. 
Unless the prototype ends in . . ., the number of arguments must match exactly. The types of the 
arguments must be identical. Additional arguments allowed by the . . . are not checked. 





If no prototype is in effect when a function is called, the "null" prototype (...) is assumed. 
However, if the Require Prototypes option is checked, and the function is not a built-in Macintosh 
call, an error is signalled. 


If no prototype is in effect when a function is defined, the "null" prototype (...) is assumed. 
However, if the Require Prototypes option is checked, an error is signalled. | 


Prototypes are optional (unless you have checked Require Prototypes), but if supplied must appear 
before the first definition or use of the function. A function definition is not itself a prototype, so the 
following example will not work: 
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£(0); 
} 


The 0 argument will be passed to £ as an int, nota long. To get automatic type coercion, a separate 
prototype—int f(long)—must be supplied before the function f is called. 


You can supply prototype information for a built-in Macintosh call; it will be checked against the built- 
in size and count information, and the prototype will subsequently be used in preference to the built-in 
information. For example: 


extern pascal Handle GetResource(OSType, int); 


Full prototype information is not built in for the Macintosh calls. 


-"Require Prototypes" Option 


This option forces very strict type checking. When set, you can neither define nor use any function 
(except for built-in Macintosh calls) without providing a prototype first. By default, the option is not 
set. 


To take best advantage of this feature, place all your prototypes in include-files so that all definitions 
and uses of functions will be checked against the same specification. 


"Check Pointer Types" Option 


This option is set by default. If it is cleared, all pointer types are considered compatible, and the 
"pointer types do not match" error message is not generated. (However, when subtracting 
two pointers, the two types must be pointers to objects of the same size.) 
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The Inline Assembler 


Assembly Syntax 


Assembly language statements may be interspersed with C code. The syntax is as follows: 


asm { 
; assembly instructions, one per line 


} 


This is syntactically a C statement and can appear anywhere a statement can; therefore, it must appear 
inside of a function definition. End-of-line is significant: only one assembly instruction can appear on 
each line. Assembly-style semicolon-to-end-of-line comments are allowed. But it's still C, so C-style 
comments are also recognized, as are preprocessor commands. Preprocessor macros are expanded 
whenever they appear. 


Standard MC68000 assembly syntax conventions are followed with a few exceptions. All instructions 
are available, as is the DC ("define constant") directive to place literal values in the code stream. No 
other assembly directives are recognized; use C to declare data, to define symbolic constants, and to 
import and export symbols. The assembler is case-insensitive with respect to instruction mnemonics, 
register names, and size specifications (.B, .W, . S, . L). 


Arbitrary C constant expressions may appear wherever a constant would be legal. 


Use of C Identifiers 


C identifiers may be referenced by name in inline assembly. The base register (A6 for locals, A5 or A4 
for globals) is optional, but if supplied it must be correct. Fields of structure variables may also be 
referenced directly. Register variables may be referenced by name wherever a register would be legal. 
The assembler is case-sensitive with respect to C identifiers. | 


C identifiers which conflict with register names (DO-D7, AO-A7, SP, USP, SR, and CCR) cannot be 
referenced by name in inline assembly. 


Offsets of fields in a structure may be referred to symbolically using the macro OF FSET, defined in 
asm.h. For example, 


long refcon(wp) /* same as "GetWRefCon"  */ 
WindowPtr wp; 
{ 


asm { | 
move.1l wp,aO 
move.1l OFFSET (WindowRecord,refCon) (a0),d0 
} 
) 
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Note, however, that fields of variables may be referenced directly, e.g.: 


long myRefcon() /* refCon of myWindow  */ 
{ 
extern WindowRecord myWindow; 
asm { 
move .1 myWindow.refCon, do 
} /* same as "return(myWindow.refCon)"! */ 


) 


In inline assembly, no implicit declaration is made for the identifier appearing in a JSR. All functions 
must be declared before they can be used in a JSR statement. 


Labels and Branching 


Instructions may be labelled with C or assembler labels. Assembler labels consist of an at-sign (@) 
followed by one or more digits; a colon is optional following an assembler label. C labels may appear 
within inline assembly; they must be followed by a colon in accordance with the C syntax. You may 
goto such a label from C code! It is also possible to refer to a C label from inline assembly, whether 
the label appears in assembly code or in C code, but the label must be preceded by @ to indicate to the 
assembler that itis a label. (This is necessary to avoid ambiguity in statements such as: LEA FOO, 
A1.) 


Certain C statements that branch are also allowed inside inline assembly: 


break ; exits the surrounding loop or switch 
continue ; skips to next iteration of the surrounding loop 
return ; exits function 


goto label; same as "bra @label" 


Do not use the RTS instruction unless you are absolutely sure you know what you are doing. Use 
return, or simply "fall through" to the end of the function, to clean up the C stack frame properly. 
Do not specify a return value in the return statement; if the function returns a value, place it in the 
proper place (usually DO) before returning. (Refer to Chapter 9 of the User's Manual for information 
on calling conventions.) 


A short branch (BRA. S) to the immediately following instruction is an error which is not detected by 
the inline assembler. (It generates an 8-bit zero displacement, which results in the next instruction word 
being used as a 16-bit displacement for a long branch rather than being executed as an instruction. 
Refer to the MC68000 manual for more details.) 


ROM Traps 


The built-in Inside Macintosh calls, except for those which are [Not in ROM], may be used as 
instructions; the appropriate trap number will be assembled. The assembler is case-sensitive with 
respect to trap names. Trap names may optionally be preceded by an underscore. Register-based traps 
are assembled inline even though they generate calls to MacTraps "glue" when used from C. (Note 
hat on 64K ROMs, Memory Manager traps do not set the low-memory global MemErr, though the 
glue does. You can force a call to the glue by using a JSR.) You can provide an optional argument, a 
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2-bit value to be placed in bits 9..10 of the trap. This allows you to set trap modifier bits, such as 
AUTOPOP,SYS,CLEAR, and ASYNC. The various trap modifier bits are defined in asm.h. For 
example: 


Handle NewSysHandle (size) 
( 


asm { 
move.l size,dO 
NewHandle CLEAR+SYS 
move.l a0,d0 


} 


When you issue a JSR to a built-in routine, the routine's identifier, like all function identifiers in inline 
assembly, must be declared before it can be used. For example: 


extern pascal void GetIndString(); 
asm { 


JSR GetIndString 


Register Usage 


You may modify registers D0, D1, D2, AO, and Al, as well as registers being used to hold register 
variables. All other registers should be saved and restored if you need them. If you want to use a 
register other than for scratch purposes, declare a register variable; you will be able to refer to it by 
name, and you won't have to bother to save and restore its value. 


If intervening C code is executed between two stretches of inline assembly, you can assume that the C 
code preserves the values of registers A5, A6, and A7—and A4 as well for drivers and code resources. 
All other registers may have been modified. It is safe to leave things on the stack while C code is 
executing, provided the stack is cleaned up before returning from the function. 


For further information on calling and register conventions, refer to Chapter 9 of the User's Manual. 


Differences From Other Assemblers 


Assembler labels are not local to the sequence of inline assembly in which they appear. Their scope 
extends throughout the function in which they appear, as C labels do. 
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The DC .B directive always generates an even number of bytes. A zero pad byte is generated if an odd 
. Jumber of values are specified. For example: 


DB "a "bito ; Assembles as four packed bytes 
DCB "a! ; These assemble as four words with 
DC.B "p" ; zero pad in the low byte 

DC.8B "eo" 

DC ea’ 


The syntax $NNNN is not available to designate a hex constant. Use the C syntax OxNNNN instead. 
The difference of two addresses is not a constant expression; therefore instructions like 
move.w #@2-@1,d0 
are not possible. Similarly, LightspeedC does not support the syntax 
dc.w Q1-* 
to assemble the PC-relative offset of the label @1. Use 
dc.w Q1 
instead. For example, to code a dispatch table, use: 
> dO contains 0,1,2,... 


add.w d0,d0 
add.w @0(d0.w),d0 


jmp Q0 (dO.w) 
GO dc.w Q1 ; case O 
dc.w 2 ; case 1 


o 
, 


The alternative syntax for PC-relative addressing—@1 (PC) instead of @1, or 81 (PC, DO) instead of 
@1 (DO) —is not supported. 


Omitting a zero displacement in the Address Register Indirect with Index addressing mode— 
(A1,D2.W) instead of 0 (A1, D2.W) —is not supported. 


Syntax for Absolute Variables 


There is a new syntax for defining absolute variables, such as low-memory globals. Previously, one 
used, e.g.: 


define MemErr * (int *) 0x220 
The following can now also be used: 


extern int MemErr : 0x220; 
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Both forms work in C, but only the new form allows low-memory globals to be used in inline 
assembly. The Macintosh include-files have been updated to use the new syntax. This feature is not 
supported for absolute variables at locations greater than OxFFFF. 


Redeclaring Built-In Functions 


Previously, redeclaring a built-in Macintosh call caused the internal definition to be overridden. It was 
therefore necessary to use 


#define NewHandle (Handle) NewHandle 
#define FrontWindow (WindowPtr) FrontWindow 


though it might be considered more natural to use 


extern pascal Handle NewHandle(); 
extern pascal WindowPtr FrontWindow() ; 


The latter would override the built-in definitions, preventing the argument checking which would 
normally be done, and leading to a link error "undefined: FrontWindow". 


This has been fixed, and the Macintosh include-files have been updated to use the new syntax. Note 
that built-in functions can still be overridden by providing definitions for them, or by declaring them to 
be C (rather than pasca 1) functions. 
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5 
Running with Switcher 


Note: Switcher version 5.0 or greater is reguired to use the Switcher-Run feature. Do not use 
LightspeedC with earlier versions of Switcher. 


If you run LightspeedC under Switcher, when you Run (ÆR) your project it is placed into a Switcher 
partition allocated from LightspeedC's own memory. When execution of your project terminates, you 
are returned to LightspeedC instantly! Transfer... behaves similarly, running a selected application 
rather than the project. 


Furthermore, during execution you can switch back to LightspeedC by clicking in the Switcher arrow at 
the upper right portion of the screen. You can now view your sources, edit files, etc. Your project 
remains in its partition; you can switch back to it by selecting Resume (R) from the Project menu 
(the Run command changes to Resume). You can switch back and forth between LightspeedC and 
your executing project in this way. While in LightspeedC, you cannot compile or do anything else 
which might modify the project. Nor can you close the project, or Quit ($Q) or Transfer..., since 
that would leave the executing project in limbo. 


You will discover that your project is running in a Switcher partition which only LightspeedC knows 
about. If you return to Switcher itself, you will not see it listed among the current applications. You 
. cannot switch to the project by using the Switcher arrows: the only way to switch to it is to use the 
Resume command from LightspeedC. Once you've Resumed, the Switcher arrows will only switch 
you back to LightspeedC. 


Before Switcher-Running your project, LightspeedC saves all modified edit windows, just as it does 
normally for Run, but it does not close them. If you have the Confirm Saves option checked, you 
are asked whether this is OK. You are asked only once for all the files. Note that clicking No does not 
mean that pending edits will be discarded, only that they will remain pending. (Of course, pending 
edits will be lost if your program crashes so badly that it cannot return to LightspeedC.) 


LightspeedC allocates as much memory as it can for your project to Run. It reserves a little extra for 
itself, so that there will be enough memory to edit files in. To be sure, though, you might want to open 
any files that you may want to edit while the project is running before issuing the Run command. 
Conversely, if you have a lot of files open you might need to close some first so that the project will 
have enough memory to run. 


The Switcher-Run feature is of limited usefulness on a 512K Macintosh. Only small projects (such as 
desk accessories) can be developed in this way. Accordingly, LightspeedC comes pre-configured for 
use with Switcher on a 1024K Macintosh; if you try to run it under Switcher on a 512K Macintosh you 
will be told "there is not enough memory to do that". To run LightspeedC under Switcher on a 512K 
Macintosh, use the Switcher command Configure then Install...; allocate LightspeedC as much 
memory as Switcher will let you. 


LightspeedC's use of Æ[ and Æ] for the Shift Left and Shift Right commands conflicts with 
Switcher's use of these key combinations to cycle among the active tasks running under Switcher. 
. Therefore, you should check Disable Keyboard Switching in Switcher's Options... dialog. 
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Programs that do not respond properly to update events, or that do not use windows, may not redisplay 
their screens correctly after switching out and back in. (The Pongerang demo distributed with 
LightspeedC is such a program.) 


Caution: Do not Quit from Switcher without first Quitting from LightspeedC. Crashes will result. 
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6 
Drivers and Code Resources 


Running a Desk Accessory 


The Run (ÆR) command in the Project menu is now enabled for desk accessory projects. The DA is 
built (exactly as by Build Desk Accessory...), and then a DA shell program is launched. The shell 
program is called DAShell and must appear in the same volume (and folder under HFS) as 
LightspeedC itself. 


The DA shell does little besides support desk accessories. Your DA appears in the @ menu, as do all 
system DA's except for those whose name or number (12) conflict with yours. When you quit the shell 
you will return to LightspeedC. To test goodbye-kisses without returning to LightspeedC, the shell has 
a Relaunch command which restarts the shell. 


Global Data Area in Drivers 


—Jsually, your driver gets control when the function main is called by the Device’ Manager, as 
described in Chapter 9 of the User's Manual. If any routine in your driver is called in any other way, 
address register A4 will not be set up to point to the global data area, and your global variables will not 
be accessible. 


For example, suppose your driver puts up a dialog box and you supply a dialog filter procedure (refer 
to the "Dialog Manager" chapter of Inside Macintosh for details): 


engage in dialog () 

{ 
extern pascal Boolean myFilter(); 
int item; 


ModalDialog(myFilter, &item) ; 


) 


When ModalDialog calls the filter procedure, register A4 may not point to your global area. The 
solution is to use SeCUpA4 and RestoreA4: 
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pascal Boolean myFilter(dp, eventp, itemp) 
DialogPtr dp; 

EventRecord *eventp; 

int *itemp; 

{ 


Boolean result; 
SetUpA4 () ; 


RestoreA4 () ; 
return(result); 


} 


The same holds for other call-back routines. Of course, if your routine does not need to access your 
driver's globals, you needn't bother to call Set UpA4 and RestoreA4. 


SetUpA4 and RestoreAA are in the MacTraps library, even though they are not described in Inside 
Macintosh. They are analogous to Set UpA5 and RestoreAS5 (described in the "OS Utilities" 
chapter of /nside Macintosh), which an application program uses to gain access to its globals from an 
interrupt handler such as a completion routine. (The Toolbox always makes sure register A5 is set up 
when calling an ordinary call-back routine such as a filter procedure, so applications don't ordinarily 
need to use these routines.) 


The sample desk accessory Windows included with LightspeedC illustrates the use of Set UpA4 and 
RestoreAA to allow access to the driver's globals from within a trap intercept routine. 


Global Data Area in Code Resources 


Code resources may now have global and static data. As in the case of drivers, the global data area is 
addressed off of A4. Unfortunately, A4 is not set up automatically as it is with drivers; you have to 
take care of it by yourself. When main is called, AO points to the global data area. Therefore, AO 
must be moved into A4. One way to do this is: 


define SetUpA4 () asm (move.l a4,-(sp) M 
move.l a0,a4} 
define RestoreA4() asm (move.l (sp)*,a4 > 


Use SetUpA4 () immediately when main is entered, and use RestoreA4 () before returning. 
(Note that these #defines are not the same as the functions SetUpA4 () and RestoreAA() 


described in the preceding section about "Global Data Area in Drivers", but are named the same to 
reflect their similar functionality.) — 
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This isn't enough if you reguire a callback routine (e.g. filter proc) to have access to your globals. This 
-somewhat more complex scheme will do the job: 


define RememberA4() A4 (1) 
#define SetUpA4 () asm { move.l a4,-(sp) ); _A4 (0) 
#define RestoreA4() asm ( move.l (sp)+,a4 } 


_A4 (remember) 
{ 


asm { 
bra.s Q1 
save: do. 0 ; keep saved A4 here 
Q1 lea @save,al 


if (remember) 

asm { move.l a0, (al) } 
else 

asm ( move.l (al),a4 } 


} 


Use RememberA4 () immediately when main is entered, then use SetUpA4 () and RestoreAA () 
as required. 


"Opening" an Open Driver 


The open entry point of a driver (main's third argument = 0) may be called even if the driver is 
already open. This happens, for example, when the user selects from the & menu the name of a desk 
accessory that's already on the screen. The driver should check to see if it is already open and avoid 
repeating its initialization sequence if so. | | 


Chapter 9 of the User's Manual recommends setting the fields of the device control entry directly in 
order to inform the Device Manager that the driver must be locked between calls, needs to be called 
periodically, etc. But the Device Manager copies the dCt 1Flags, dCtlMenu, dCtlDelay, and 
dCtlEMask fields of the driver's header to the corresponding fields of the device control entry each 
time the driver is opened, even if it is already open. Therefore these fields must be set to their proper 
values each time. The open routine of the driver (called from main when the third argument is 0) 
should look something like this: 


doOpen () 
( 
dce->dCtlFlags|= dNeedLocked; /* or whatever  */ 
if (already open) 
return; 
already open = 1; 
/* one-time initialization  */ 
} 


~ The sample desk accessory Windows included with LightspeedC illustrates this technique. 
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Open/Close Result Codes in Drivers 


The new ROM supports result codes passed back from the Open and Close entries. If a negative result 
is returned from the Open entry, the driver is not opened; if closeErr (-24) is returned from the 
Close entry, the driver is not closed. 


The LightspeedC interface glue now recognizes these cases and manages the DATA resource, used to 
store the driver's global data, correctly. 


Warning: For your drivers to work correctly on 64K ROMS, you must be sure to return zero from your 
Open and Close entries. (Previously, it didn't matter what you returned.) 


An additional special case is recognized: if 1 (one) is returned from the Close entry, the handle in the 
dCtlStorage field of the device control entry is not deallocated. A result code of zero is actually 
returned to the Device Manager. You might use this to keep your globals around until the driver is re- 
opened. 


Runtime Routines in Code Resources 


Some 4004 bytes of runtime routines are linked into code resources to implement the switch 
statement and the multiply, divide, and modulo operations on 1ong operands. Previously, these 
routines were always linked in. Now, they are linked in only if they are needed. (However, the 
routines are a unit, so if any routine is used, they are all linked in.) This optimization applies to code 
resources only. 


Additional Header Information for Drivers and Code Resources 


The resource name of a desk accessory or device driver is now placed in the driver header beginning at 
offset 18. Exactly 32 bytes are reserved in the header for this purpose, so names longer than 31 
characters are truncated. 


Six bytes of resource type and ID are now placed starting at offset 4 of a code resource. Additionally, 
the two bytes starting at offset 2 and the six bytes starting at offset 10 are set to zero; these are unused 
and may be patched as desired. 
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7 
Libraries 


128K ROM and HFS support 


LightspeedC has been fully upgraded to conform to Volume 4 of Inside Macintosh. The new calls are 
recognized and argument-checked in the usual way. The MacTraps library and the Macintosh include- 
files have been updated appropriately; files HFS.h, ListMgr.h, SCSIMgr.h, and TimeMgr.h are 
new. There are several minor issues which bear mentioning: 


* The new Toolbox Utilities routines Fix2X and Frac2X return SANE Extended 
(equivalent to LightspeedC double). Their Pascal declarations are: 


FUNCTION Fix2X (x:Fixed): Extended; 
FUNCTION Frac2X (x:Fract): Extended; 


Unfortunately, returning an Extended type is illegal for a pascal routine in 
LightspeedC. Instead these must be called as C functions (via glue in Mactraps). 
Before calling them, they must be declared as follows: 


double Fix2X(Fixed); 
double Frac2X(Fract); 


ToolboxUtil.h contains these declarations. (If you forget these declarations, you will 
get the error "wrong number of arguments".) If you prefer, they can be called 
directly from inline assembly. 


e The List Manager function LLastClick returns a Cell (same as a Point); this is 
also illegal for a pascal function. In LightspeedC, it returns a 1ong instead. 


* The new File Manager chapter in Volume 4 of Inside Macintosh gives definitions for 
the types VCB, Dr vOEl, and DrvQE1Ptr which conflict with the original 
definitions. The new types have instead been defined as HVCB, HDrvQE1, and 
HD wh 1Ptr so that both the original and current definitions of these types are 
available. 


Other Macintosh Library Changes 


e In Release 1.02, SetUpA5 and RestoreA5 were functions in the MacTraps 
library. In Release 2.01, they are macros in the header file OSUtil.h. Be sure to 
include OSUtil.h when you want to use Set UpA5 and RestoreAS. 
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* Glue for the Launch and Chain traps is provided in MacTraps and can be called from 
LightspeedC: 


pascal void Launch(int config, char *filename); 
pascal void Chain(int config, char *filename); 


* Interfaces for the RAM Serial Drivers are provided in the MacTraps library. 
Interfaces for Appletalk are provided in the Appletalk.Lib library. However, to use 
either of these facilities, additional resources must be included in the resource file for 
your program. These resources are supplied with LightspeedC in the following two 
files: 


SERD which contains RAM Serial Driver resources 
ATalk/ABPackage | which contains Appletalk resources 


* The pascal.h file may be found in the Mac #includes folder and contains the 
declarations for the following functions: 


pascal void CallPascal(); 
pascal char CallPascalB(); 
pascal int CallPascalW(); 
pascal long CallPascalL(); 
char *OCtoPstr(ü; 

char *PtoCstr(); 


These functions are in the MacTraps library, even though they they are not described 
in Inside Macintosh. This file should be included whenever any of these functions 
are used. (See "Making Indirect Calls" in Chapter 9 of the User's Manual.) 


Enhancements to Standard C Libraries 


All projects that contained only one file have been changed to libraries to save space on the disk. These 
libraries are: math, storage, storageu, strings, and unix strings. To rebuild one of these libraries, 
create a New project, Add the corresponding source file, and Build Library.... 


The source code to the libraries has grown, but in general the object size has shrunk somewhat due to 
code improvements, except for printf-2-w.c, which adds about 4K to stdio for the new window 
functions described below. If you would rather use the old version, replace printf-2-w.c with printf- 
2.c in stdio, recompile, and reload the stdio library. 


The strings library has been rewritten in assembly language for efficiency. The source code is 
provided as stringsasm.c. The old version is provided as strings.c for those who still want to have 
Macsbug symbols or use the profiler with these functions. 


proto.h contains function prototypes for use with the math, stdio, storage, storageu, strings, 
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unix, and unix strings libraries. Its use is optional, but is useful if you check the Require 
Function Prototypes option. If you choose to use it, please note that it complements, but does not 
~ replace, the usual include-files for each library. 


There are many new features and functions in the stdio library. A real Macintosh window titled 
"console" is automatically created for plain C applications the first time keyboard input or screen 
output is requested through the Standard I/O functions. In addition, @, File and and Edit menus are 
added to the menu bar. Whenever keyboard input is expected, the commands in the menu bar created 
by the stdio library can be accessed. Open in the File menu will show the console window if it is 
hidden. Close in the File menu when the console window is frontmost (or clicking in its close box) 
will hide it; Close in the File menu when any other stdio window is frontmost (or clicking in its 
close box) will execute an fclose on that window. Quit in the File menu will do an 
ExitToShell. Also, when keyboard input is expected, desk accessories and FKEYs can be 
accessed. 


Support for use of device drivers has been added to stdio. Device driver names can be passed to 
fopen and will be handled correctly. This has been done primarily to allow the use of the four 
standard Macintosh serial drivers (. AIn, . AOut, . BIn, .BOut); this allows the use of stdio with 
printers, modems, etc. 


A new library, sprintf/sscanf, is provided. It is a subset of stdio allowing you to use the sprintf 
and sscanf functions in your programs without having to load the large stdio library into your 
project. Stdio itself has been better modularized, so that when a project is built into an application, 
many more unused functions will be stripped out by the linker than in release 1.02. 

Note: The libraries stdio and sprintf/sscanf contain the library setjmp.Lib. If your project uses the 
~setjmp and long jmp routines as well as stdio or sprintf/sscanf, do not explicitly add the 
setjmp.Lib library. 


The unix library has also been enhanced to provide additional Unix emulation. 


New Standard C Library Functions 


The following pages describe some new library functions: 
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abort 


break to a debugger or exit 


(unix) 
SYNTAX #include <stdio.h> 
void abort () 
DESCRIPTION Abort automatically breaks to a debugger if one is present; otherwise the 
program is exited. 
Page 31 
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— enable/disable "Click to Continue" on exit Click on 


(stdio) 


SYNTAX | #include <stdio.h> 
void Click On(flag) 
Boolean flag; 


DESCRIPTION This function controls the "click mouse to continue" option. If £1ag is 1, 
the option is enabled; if flag is 0 the option is disabled. If this option is 
enabled, when a program that uses stdio terminates, a window (titled 
"Exit Window") will appear. Only when the user clicks in the close 
box, presses the return key, or (if the menus were created by stdio) 
selects the Quit command from the File menu will the program actually 
exit. This option is initially enabled. 
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turn printer echo on or off Echo to Printer 
(stdio) 


SYNTAX #include «stdio.h» 


void Echo to Printer(flag) 
Boolean flag; 


DESCRIPTION Call this function with the argument TRUE to turn on printer echoing. 
When printer echoing is on, the console window text output will be 
echoed to the printer. If input is being echoed to the console window, it 


will be echoed to the printer as well. 
Call this function with the argument FALSE to turn off printer echoing. 
This is the default condition. 
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launch a program 


SYNTAX 


DESCRIPTION 


RETURN VALUE 


execl 
execv 
execle 
execve 
(unix) 


#include «stdio.h» 


int execl (path) 
char *path; 


int execv(path, argv) 
char *path; char *argv[]; 


int execle (path) 
char “path; 


int execve (path, argv, envp) 
char “path, *argv[], *envp[]; 


These functions just launch the file name indicated by path. There is no 
support for arguments or environment variables. (Refer to the System V 
Unix manual for a complete explanation.) 


These functions never return. 
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open a new stdio window fo D enw 


SYNTAX 


DESCRIPTION 


RETURN VALUE 


(stdio) 


#include <stdio.h> 

FILE *fopenw(title, upperLeftCorner, optionsPtr) 
char *title; 

Point upperLeftCorner; 

StdWindowOptions *optionsPtr; 


fopenw opens a new window with the specified title at the designated 
position (in global coordinates). 


optionsPtr is a pointer to a StdWindowOptions structure as 
defined in fopenw.h. If the pointer is NULL (OL), then the window will 
be created with the following defaults: a 24-by-80 window, visible 
cursor, input echoed, tab width of 4 spaces, window brought forward on 
output to it (including echoing of input), grow box, draggable, go-away 
box, scrolling, and line wrap-around. (On big-screen Macintoshes, the 
default screen will be larger. After calling £openw () , the memory 
pointed to by optionsPtr is no longer needed. 


Returns an ordinary FILE pointer variable which can be passed to 
fprintf, fclose, etc. | 
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get cursor position getxpos 


getypos 
(stdio) 


SYNTAX #include <stdio.h> 
int getxpos() 
int getypos() 


DESCRIPTION These functions return the x and y coordinates of the cursor in the current 
window. 


RETURN VALUE xory coordinates of the cursor. 


SEE ALSO setwindow 
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get the screen buffer of stdio window Get S creenPtr 
(stdio) 


SYNTAX #include «stdio.h» 


char “Get ScreenPtr(windowFileVar) 
FILE *windowFileVar; 


DESCRIPTION This function returns the address of the screen buffer for the window 
associated with the FILE variable windowFileVar. The buffer can be 
treated as a two-dimensional array of characters whose size is given by the 
maxcol and maxrow fields of the StdWindowOptions structure 
defined in fopenw.h. 


RETURN VALUE The address of the screen buffer associated with windowFileVar. 
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— generate a signal kill 


(unix) 
SYNTAX #include «stdio.h» 
int kill(pid, sig) 
int pid, int sig; 
DESCRIPTION This generates a signal. Use getpid to determine the right value for 


pid. 


RETURN VALUE 0if successful, -1 otherwise (errno contains the actual error number). 
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set the current stdio window | Se tw | n d OW 
(stdio) 


SYNTAX #include «stdio.h» 


void setwindow(windowFileVar) 
FILE *windowFileVar; 


DESCRIPTION The specified FILE variable becomes the "current" window. The 
functions Set Echo, Set Tab, gotoxy,getxpos, getypos, and 
wputs implicitly apply to the current window. 


(Functions which implicitly apply to stdout, such as print f, or to the 
console, such as cprintf, are not affected by which window is 
current.) 


Initially, stdout is the current window. fopenw does not make the 
new window the current window. 
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—— 


set a signal 


SYNTAX 


DESCRIPTION 


RETURN VALUE 


signal 
(unix) 


#include <stdio.h> 

int (*signal(sig, func) ) () 
int sid; 

int (*func) 0; 


Setting the SIGINT signal allows 38C and Æ. (command-period) to be 
trapped. Setting the SIGTERM signal is just like calling onexit. Other 
signals can be set, but are only generated by explicit calls to ki11. Each 
signal is automatically reset to SIG DFL once invoked. 


Signals set to SIG IGN are ignored. All signals are initially set to 


SIG IGN. Signals set to SIG DFL will cause the program to exit, or 
will break to the debugger if one 1s present. 


The previous function set for sig. 
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handle event in a stdio window StdEvent 
(stdio) 


SYNTAX #include «stdio.h» 


Boolean StdEvent (theEvent) 
EventRecord *theEvent; 


DESCRIPTION Passed a pointer to an event record, this procedure determines if the event 
relates to one of the windows created with fopenw. If so, it handles the 
event and returns TRUE; otherwise it returns FALSE. If your application 
has its own event loop, you should call StdEvent after calling 
GetNextEvent, and handle the event yourself only if St dEvent 
returns FALSE. 


RETURN VALUE TRUE if event relates to stdio window, FALSE otherwise. 


LightspeedC Release 2.01 Supplement Page 41 
Copyright O 1986 THINK Technologies, Inc. 


 nhibit stdio initialization Stdio MaclInit 
(stdio) 


SYNTAX #include <stdio.h> 


void Stdio MacInit (flag) 
Boolean flag; 


DESCRIPTION To prevent stdio functions from calling InitGraf, InitFonts, 
InitWindows, InitDialogs, TEInit, and InitMenus, and from 
setting up the stdio menus, etc., call this function with the argument 
TRUE prior to any stdio calls. This will allow you to use stdio windows 
without conflicting with your application's own windows and menus. 
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get version of stdio library : std ver 


(stdio) 


SYNTAX #include <stdio.h> 
char “std ver() 


DESCRIPTION This returns a pointer to a string containing the version specification of the 
stdio library. This string is currently "LightspeedC™ Libraries 
i257", 


RETURN VALUE String representation of stdio library version. 
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wputs 
(stdio) 


vrite a string into the current stdio window 


SYNTAX #include <stdio.h> 
void wputs(s) 
char *s; 
DESCRIPTION This is the same as cputs, but output goes to the current window rather 


than to the console window. 


SEE ALSO setwindow 
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8 
Tips from Customer Support 


We at THINK Technologies want our users to get the most out of LightspeedC. This means providing 
comprehensive customer support, Something we try hard to do. We discovered soon after our first 
LightspeedC release that there were a few issues that were not clearly covered by our documentation, so 
this chapter tries to address some of these. 
The following is included in this chapter: 

* suggested layouts for various hardware configurations 


e a Step-by-step illustration of the process of creating a program—the famous Kernighan and 
Ritchie "hello, world" example 


e alist of many frequently encountered problems 

* tips and suggestions about avoiding errors and improving code 

* acouple of examples of Grep usage 

e alist of a few books you might find useful 

| So, before calling THINK Customer Support, please check this chapter to see if your question is 
answered here. If you still have a situation you can't figure out, don't hesitate to call us at (617) 


863—1099—that's what we're here for. Our customer support hours are from 9:00 AM to 5:00 PM 
Eastern Time. 
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Recommended Disk Layouts 


The following are some suggested disk layouts for various hardware configurations. If you don't have 
enough room for a big system file and your LightspeedC files, remove unneeded fonts and desk 
accessories from the system file using Font/DA Mover. If you're using HFS, files may be put into 


sub-directories within the suggested folders as you see fit. 
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For two 400K disks, primarily using the Standard C libraries such as stdio for printf: 
Disk 1: System Folder (including System and Finder); LightspeedC™ and MacTraps 
from the LS1.System disk; and the Zincludes files folder and any C libraries you need from 
the LS2.Libraries disk. Do not copy the Library Sources folder: you won't have enough 
disk space. See Chapter 13 of the User's Manual to find out which library a function is in. 


Disk 2: Your project and its source and header files, plus any libraries and include-files you 
need that would not fit on Disk 1. 


For two 400K disks, primarily using the Macintosh libraries: 

Disk 1: System Folder (including System and Finder); LightspeedC™, MacTraps, any 
other Mac libraries and resources you need, and any files you need from the Mac #includes 
folder from the LS1.System disk. 


Disk 2: Your project and its source and header files, plus any libraries and include-files you 
need that would not fit on Disk 1. 


For one 800K disk or larger HFS volume, primarily using the Standard C libraries such as 
stdio for printf, we suggest the following: 


System Folder: System and Finder (and Imagewriter or Laserwriter files if desired). 

C Folder: LightspeedC™ and MacTraps from the LS1.System disk; and the #include 
files folders and any C libraries you want from the LS2.Libraries disk. If you have an 
800K floppy, do not copy the Library Sources folder: you won't have enough disk space. 
See Chapter 13 of the User's Manual to find out which library a function is in. 

Project folder: Your project and its source and header files. 


Since you are using HFS, do not put C Folder inside the project folder or vice versa. 


For one 800K disk or larger HFS volume, primarily using the Macintosh libraries, we 
suggest the following: 


System Folder: System and Finder (and Imagewriter or Laserwriter files if desired). 


C Folder: LightspeedC™, MacTraps, any other Mac libraries and resources you need, and 
the Mac Zincludes folder from the LS1.System disk. 


Project folder: Your project and its source and header files. 


Since you are using HFS, do not put C Folder inside the project folder or vice versa. 
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"hello, world" in LightspeedC 

-Many of our users start out by programming a simple example program from Kernighan and Ritchie's 
The C Programming Language, commonly known as "hello, world". This section explains how to get 
this example running in LightspeedC. 
1. Install LightspeedC on your system. See "Recommended Disk Layouts", above. 


2. Run LightspeedC. It will prompt you for a project with a Macintosh Standard File dialog. Click the 
button marked New. 


3. You will be asked to create your new project. Call the project hello project, and store it on a disk 
that will have room for it. (About 72K of disk space will be required for this project.) 


4. Once the project is created, select New from the File menu. A window titled "Untitled" will 
appear. Enter into the window the following program: 


#include "stdio.h" 
main() 


{ 
} 


printf("hello; world\n") ; 


5. Select Save from the File menu. A dialog box will appear asking you to name the file. Name it 
hello.c and click the Save button. (Your source files names must end in .c.) 


9. Select Compile from the Source menu. Your program will compile and will be entered in the 
| project window. 


7. Select Add... from the Source menu. Add the file stdio (to obtain access to the printf function) 
and the file MacTraps (to let the printf function have access to the Macintosh Toolbox), then 
select Cancel to end the Add... process. 


8. Select Run from the Project menu. LightspeedC will ask you if you want to bring your project up 
to date. Click the Yes button. LightspeedC will load the libraries in the project, link it and run it. It 
should display a window named "console" with the greeting "hello, world" init. 


Congratulations! You're a C programmer! 
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Some Common Problems 


Problem: Link errors. Typically, the message "not defined: printf"or something similar 
will appear in a window titled "Link Errors". 


Possible Cause 

You have not added a necessary library (using Add...). If a missing symbol is a 
Macintosh Toolbox function, it may be that MacTraps hasn't been included. The 
MacTraps library must be included in nearly all projects, since it holds the QuickDraw 
globals and "glue" code that accesses the register-based Macintosh Toolbox functions, as 
well as the [Not in ROM] routines. 


Similarly, if you're using any C library routines, you may not have included the library 
that contains the code for that routine. Check the documentation for the routine in Chapter 
13 of the LightspeedC User's Manual. You will see the routine name at the top of the 
page in large bold print. Below that, in parentheses, you will see the name of the library 
you need. Make sure that that library is added to your project, using the Add... 
command. 


Possible Cause 

You have made a spelling or capitalization error. C is a case-sensitive language, which 
means that printf is not the same as Printf. Check to see that the undefined function 
name is spelled and capitalized correctly and matches the spelling of the function in the 
manual in Chapter 13 (for C functions) or Chapter 14 (for Macintosh functions). 


Possible Cause 
You have redefined a Macintosh or C library function as "extern". For example: 


extern void SetRect(); 


Such re-definitions are unnecessary, since Toolbox function definitions are already built in 
to LightspeedC. If one appears, the linker will try to resolve the reference with a user- 
defined function. This is fine if what you want to do is replace a standard function, but 
will cause a linker error if no replacement function is provided. (If you want to supply 
return type or prototype information for Toolbox calls, see page 16 of this supplement.) 


Problem: Running the MiniEdit example gives error "Can't open resource file." 


Probable Cause 

MiniEdit needs the resources in the new project.rsrc. In order for LightspeedC to add the 
resources to the MiniEdit project, the project should be named new project. If you're 
running under HFS, both files must be in the same folder. 
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?roblem: The Link Error window says "Code segment too large". This error occurs when 


one of the segments of your project contains more than 32K of code. 


Solution | 
Move files out of the too-large segment until it contains less than 32K of code. See page 
5-3 of the User's Manual for instructions on moving files between segments. You can 
check the amount of code contained in a segment by selecting a file in the project window 
and selecting the Get Info command from the Source menu. 


Problem: Can't find an include-file. 


Possible Cause 

You have an HFS machine and the specified file is not in the correct search path. The 
basic search rules are explained on page 4-4 of the User's Manual and page 4 of this 
supplement. In this release of LightspeedC, these search rules have been expanded under 
HFS to include "all descendents of the folder being searched". 


Let's assume that you've set up your HFS file system like this: 


are 


HD-20 


in Wa d 


C My Project folder € folder 


uL uu 


LightspeedC™ *include files Mac *includes My Project My *includes orphan.h 





)-— 


stdio.h Quickdraw .h MyHeader .h 





The file Quickdraw.h can be referenced by the include directive: 


#include <Quickdraw.h> 
or the directive 


#include "Quickdraw.h" /* searches the project tree 
first */ 


The file stdio.h can be referenced by the directive: 
#include <stdio.h> 


or the directive 
#include "stdio.h" /* searches the project tree 
flrat */ 
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The file MyHeader.h can be found with the directive: 
#include "MyHeader.nh" 
but not with the directive 
#include «MyHeader.h» /* the project tree will not 
get searched for files 
enclosed in «» */ 


However, you can only reference the file orphan.h by specifying an absolute path name: 
include "HD-20:orphan folder:orphan.h" 


Problem: Bomb message saying "ID=02" (Odd Address Error) when you run your program. 
There are many possible causes here; some are very complex. A few common causes 
are: 


Possible Cause 

QuickDraw was not initialized. If your program does graphics using the Macintosh's 
QuickDraw library, the drawing environment must be initialized with a call to InitGraf. 
(See the "QuickDraw" chapter of Inside Macintosh.) Note that if you are using the stdio 
library, this initialization is done for you unless you call Stdio MacInit (TRUE) 
before any calls to stdio routines. In any event, you should not initialize QuickDraw 
twice! 


Possible Cause 

You have referenced a null handle or pointer. A null handle can result from several 
things. First, there may be a missing resource file. If your program uses a resource file 
that is not found, a Get Resource (or GetNewMenu, GetNewWindow, etc.) call will 
return a null handle. Make sure that if you have an auxiliary resource file it is on the same 
disk (and in the same folder as your project file under HFS), and that it is named «your 
project file name».rsrc. (See page 4 of this supplement.) 


Second, you may not have enough memory for a NewHandle or NewPtr call, resulting 
in a null return value. Lastly, you may have not initialized a pointer variable. 


Possible Cause 

You've called a Toolbox routine with bad or inappropriate data. For example, you are 
likely to crash if you call DisposHandle with a handle to a resource. Use 
ReleaseResource instead. 


Problem: Can' load library. 


Possible Cause 

You have an old version of the HD-20 file used in HFS systems running with old ROMs. 
If you have old ROMS (i. e. a 512K Mac which has not been upgraded) and you use an 
HD-20, you have to start your machine with a floppy disk which "kick-starts" your HD- 
20. On the floppy disk there is a system file named HD-20. The original version of this 
file (v1.0, created in September 1985) has a bug which will cause LightspeedC not to find 
libraries if they are in folders. You should get a newer version of the HD-20 file from 
your — Until you do, libraries must be on the root volume of the HD-20 to work 
correctly. 
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Oroblem: Data segment too large or stack frame too large. This error occurs when your project has 
more than 32K of global data or a function has more than 32K of local data. 


Solution 

If you want to be able to access global or local memory larger than the 32K limit imposed 
by the Macintosh/MC68000 architecture, you must allocate the memory dynamically via a 
pointer or handle. Because the C language blurs the distinction between arrays and 
pointers, you can then use the pointer with an array notation to access elements in dynamic 
memory. (Refer to a good C language manual, such as Kernighan and Ritchie's The C 
Programming Language for more details.) 


Example: 
define SIZE 100000 
#define SIZE2D 100 
int BigBadArray[SIZE]; /* a too big array */ 


int *LooksLikeAnArray; 
int BigBad2DimArray[SIZE2D][SIZE]; /*too big 2D array*/ 
int *LooksLikeA2DArray[SIZE2D]; /*array of pointers*/ 


proc () 


{ 
register long i; 


/* allocate "array"*/ 

LooksLikeAnArray = (int *)NewPtr(sizeof (int) *SIZE) ; 

LooksLikeAnArray [60000] = 5; /* can index it just 
like an array */ 


/* allocate 2D "array"*/ 
for (i «0; 1 < SIZE2ZD; itt) 
LooksLikeA2DArray[i] = 


(int *)NewPtr (sizeof (int) *SIZE); ; 


LooksLikeA2DArray[10][20] = 7; /* can index it 
just like an 
array */ 


Problem: printf and scanf don't seem to work correctly with long or double data. 


Solution 

A common misconception about printf is that printf "knows" about its arguments. 
If you pass a long expression to printf, you must specify in the format string that you 
want a long expression to be printed. Example: 


int anInt; 
long aLong; 
printf ("long is %ld, int is %td\n", aLong, anInt); 
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In scanf, the same goes for floats and doubles: 


float aFloat; 

double aDouble; 

printf (“Input a double and a float:"); 
scanf("Slf $f", &aDouble, &aFloat); 


Problem: "I included stdio.h in my source file, so why do I get a link error for print f?" 


Solution 

Many novice users (and not-so-novice users!) get confused about the difference between 
"header" files and "library" files. Header files (which conventionally have names which 
end in .h) contain source statements: definitions and declarations which allow the 
compiler to make sense of source code calls to a library function. Libraries contain the 
actual object code for the functions themselves, which the linker references in building the 
project. Including a header file is for the compiler only; it tells the linker nothing. 


#include-ing a library in a source file is an error. 





Some Useful Tips 


Arrays 


To work with arrays greater than 32K, see "Problem: Data segment too large" on page 51 of this 
supplement. 


Typically, arrays are accessed within loops, so small gains in efficiency can be greatly magnified. Here 
are a couple of tips: 


¢ Indexing of arrays whose elements are a size that is a power of two is more efficient if you 
declare the index to be of type register long. For arrays of doubles, or structs 
whose size is not a power of two, use register int. Example: 


int array[10]; 
register long FastIndex; /* int is not as fast */ 
int SlowIndex; 


array[SlowIndex] = 5; /* Slower */ 
array[FastIndex] = 5; /* Faster */ 
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e Sequential access of arrays can be done more efficiently with pointers. Further 
optimization can be done with inline assembly, if desired. Example: 


int array[MAXSIZE]; 
register int *p; 
register long i; 


/* Slower: 


index calculations (multiplication and 


additions) are done */ 


for (i = 0; i < MAXSIZE; itt) 
array[i] = i; 
/* Faster: index calculations are avoided, one addition is 
done */ 
for (i = 0, p = array; i < MAXSIZE; itt, ptt) 
* am 4 e 
p = 1, 


Inline Assembly 


Inline assembly can be tricky if you are not familiar with assembly language. It can be especially 
dangerous if you are used to thinking in terms of high-level languages. The following problems 
described are not specific to LightspeedC; they are common to assembly language in general. 


e Truncation of constants is not detected. Examples: 


add. W 
dc.W 


#0x12345678, DO ; gets truncated to 0x5678 
0x12345678 ; gets truncated to 0x5678 


e Don't forget the 4 sign when using an immediate constant. The result will be very different 
than what you intended. 


extern int MemErr : 0x220; /* declare MemErr low 


asm( 


MOVE. 


MOVE. 


MOVE 


MOVE. 


MOVE. 


} 


W 
W 
W 
W 
W 


memory global */ 


0x220, DO ;moves contents of location 0x220 
; (MemErr) into DO 
MemErr, D0;same way of writing the above 


;symbolically 

$0x220, DO;moves the value 0x220 into DO 

Sy DO ;WRONG: this will cause an odd address 
error! 

#5, DO Right 


* The assembly directive DS, which would create global storage space, is not allowed. Use 
C variables instead. If you use the directive DC instead to declare storage space, storage 


will be allocated in your code segment. Most of the time, this is not what you want, 
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* Be sure to use the right-sized instruction when referring to variables. Example: 


function() 
{ 
int anInt; 
int GetsTrashed; 


asm{ 
move.L #3, anInt ;WRONG: will overwrite 
;variable GetsTrashed 
move.W #3, anInt ;RIGHT: Word size matches int. 


} 
} 


e Quick instructions are automatically used whenever possible. Therefore, you don't have to 
painstakingly hand-optimize MOVE to MOVEQ instructions. Examples: 


MOVE.L #4, DO 
MOVEQ #4, DO 
ADD .L #aConstant, DO 


This instruction assembles as... 
...Which is faster and smaller. 
You don't even have to know if 
aConstant is the right size for 
a Quick instruction. 

An ADDO is generated if 1 <= 
aConstant <= 8 * 


™e “Be Boe Be Be Be Be 


e Make sure your code doesn't run into your DC's. Example: 


MOVE.W @valuel, DO 
@valuel: DC.W -1 ; WRONG: the Macintosh will try to 
; execute this "instruction" 
; following the MOVE.W instruction 


MOVE.W @value2, DO 

BRA.S Q1 ; RIGHT: branch around inline data. 
Qvalue2: DC.W -1 
B1 


Floating Point Arithmetic 


The LightspeedC type double actually corresponds to the SANE type Extended. This type takes up 
10 bytes of storage, but is the fastest floating point type. Conversely, the LightspeedC type float 
actually corresponds to the SANE type Single. This type takes up 4 bytes of storage, but is the second 
fastest floating point type. The LightspeedC type short double actually corresponds to the SANE 
type Double. This type takes up 8 bytes of storage, but strangely enough is the slowest floating point 
type. If you want speed, stick with double. If you want to save space and are willing to sacrifice 
some accuracy and speed, then use float. If you are willing to sacrifice more accuracy for speed, 
consider using the fixed math library. 


Some other suggestions: 


* Infloating point operations, use floating point constants. Example: 
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doublel = double2 * 5; /* Slower: 5 has to be converted 
to double at runtime */ 
doublel = double2 * 5.0; /* Faster: 5.0 doesn't have 


to be converted */ 
* Multiplication is faster than division. Example: 


doublel - double2 / 5.0; /* Slower */ 
doublel = double2 * 0.2; /* Faster */ 


And of course addition is faster than multiplication by 2: 


double2 * 2.0; /* Slower */ 
double2 + double2;  /* Faster */ 


doublel 
doublel 


e Use the +=, *=, etc. operators wherever possible. Due to the way SANE works, storing 
the result of a floating point operation into an operand's memory is more efficient. 
Example: 


double result, a, b, c; 


result = a * b * c; /* Slower and larger */ 

result = a; /* Faster and smaller: avoids 
temp variables */ 

result *= b; 

result *-2 c; 


* Evaluate floating point constant expressions. LightspeedC does not pre-calculate constant 
floating point expressions at compile time. (To do so, LightspeedC would have to make 
assumptions about what the SANE environment will be at runtime.) Example: 


doublel *= 4.5 + 2.4; /* Slower: the addition is 
done at run time */ 
doublel *= 6.9; /* Faster */ 


e It's better to return a double variable than a double expression. Example: 
returní(aLocalDouble + 4.0); /*Larger and slightly slower*/ 
aLocalDouble += 4.0; /*Smaller and slightly faster*/ 
return (aLocalDouble) ; 

Efficiency 

e SetRect, SetPt, etc., take more time than setting up the coordinates yourself, because 

of the overhead of the Macintosh trap dispatcher. However, significant improvements will 


be noticed only if you are executing lots of them. 


* Use register variables whenever a local variable or parameter is used more than a few times 
or is heavily used in a loop. 
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* The fastest way to do something N times is: 
register int i; /* will not work if i is unsigned! */ 


i - N; 
while (--i >= 0) 
something(); 


e Bitfield variables save storage space, but it takes more time and code space to access the 
data in bitfield variables larger than one bit. However, the setting and clearing of single 
bits uses the same amount of code space. 


Memory Management 


* If you are dereferencing Handles, then make sure that the memory the Handle points to 
won't move while using it. Otherwise, HLock it (and HUnlock itlater). Example: 


HLock (aTEH) ; 
/* Without the previous HLock, the next two calls may 
not always work*/ 
/*(1) printf calls Memory Mgr: */ 
printf("first character in text handle is %c\n", 
**(**aTEH).hText >); 
/*(2) Handle dereference on the left is done BEFORE call:*/ 
(**aTEH).hText = (Handle) NewHandle (somesize) ; 
HUnlock (aTEH) ; 


* To increase your zone (the memory available to your program) to the maximum, call the 
procedure MaxApplZone(). 


Miscellaneous 


e Don't forget to make all necessary Macintosh initialization calls. In LightspeedC, you must 
make all the necessary calls yourself. (Some other Macintosh C compilers do some 
initializations for you.) 


An exception to this occurs when using the stdio library. Initializations are automatically 
done the first time a stdio procedure (that needs it) is called. You can turn this off if you 
are doing your own initializations—for example, if you are using the standard output 
window for debugging. The automatic initialization is for users of LightspeedC who want 
to have the more traditional, non-Macintosh C environment. See "Enhancements to 
Standard C Libraries" on page 29 of this supplement. 


* The Byte and Char types in Pascal actually correspond to the int type in C. The three 
places that this has caused our users problems are the functions ATPOpenSocket, 
GetItemMark, and GetItemIcon. In these functions, a Byte argument is passed by 
reference. The proper way to do this in C is to pass a pointer to an int. 


e TMON doesn't know that the DebugStr trap (OxABFF) takes a string argument and 
doesn't clean up the stack correctly. Don't use DebugStr if TMON is your debugger. 
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Some Grep Examples 
Here is a grep example useful for converting assembly language to LightspeedC inline: 
e To convert 


symbol equ (expression+4) ; a comment 


to 


#define symbol (expression+4) /* ; a comment */ 


grep-search for 

X(N&€, ,*N9X) [space tab] *\<egqu\>\ [nT ANNAN C.N) 
and replace with 

#define N1 N2 /* M3 */ 


Explanation: 

° \<..%*\> matches a symbol. 
The surrounding \ ( and \) allows the symbol to be in the replacement string 
as A1. 
The [space tab] * matches any number of spaces or tabs between the symbol 
and the key word equ. 
i \<equ\> matches the word equ. It will not match equ if it is part of another 
word, for example equal. \<equ\> is not surrounded by \ ( and \) 
because it will be thrown away in the replacement string. 
[*; ] * matches an expression formed by any number of characters up to but 
not including a ; (semi-colon). | 
The surrounding * ( and \) allows the expression to be remembered in the 
replacement string as 2. 
The . * matches the comment which is the rest of the line. 
The surrounding \ ( and \) allows the comment to be remembered in the 
replacement string as 3. 
If there was no ; (semi-colon) in the line, then \2 will consist of everything 
after the equ to the end of the line and \3 will be an empty string. 
° To insert a tab in the Find... dialog, type Tab (Command-Tab). 


o 
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* Toconvert SHHHH to OxHHHH, where H is a hexadecimal digit, grep search for 
$N([0-9A-Fa-£] [0-9A-Fa-£] *\) 
and replace with 
Ox\1 


Explanation: | 

° $matchesa $. [0-9A-Fa-f] matches one hex digit. 
[0-9A-Fa-f£] [0-9A-Fa- f] * matches one or more hex digits. (The grep 
search string [0- 9A-Fa-£] * matches zero or more hex digits.) 
The surrounding \ ( and \) allows the hex digits to be remembered in the 
replacement string as M1. 


o 


o 


If you like, save complicated grep search and replace strings in a file so you can copy and paste them 
into the Find... dialog box. 


Further Reading 
* Inside Macintosh is, of course, vital. 


e If you want to make your program smaller or run faster, an excellent place to start is by 
reading Writing Efficient Programs by Jon Louis Bentley (Prentice-Hall 1982). In most 
compute-bound programs, about 5046 of the time is spent in about 470 of the code. Most 
code optimizations don't optimize as much as you might think. Although the suggestions 
in here may not produce large improvements, they are relatively cheap to put in. 


e We highly recommend the book How to Write Macintosh Software by Scott Knaster 
(Hayden Book Company 1986) for many useful tips, tricks and warnings about 
programming the Macintosh. 


* The book Using the Macintosh Toolbox with C by Jim Takatsuka et al. (SYBEX 1986) is 
a good introduction. However, be aware that it emphasizes Consulair's Mac C rather than 
LightspeedC, so some examples will have to be modified (see Chapter 10 of the User's 
Manual for notes about translating from other C's to LightspeedC). 
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Appendix A 
Corrections to the User's Manual 


page 1-1; 
The compile times claimed should read: 

"A typical 15,000 line program in 20 source files (XLISP V1.4) takes slightly more than three 
minutes to compile on a 10-megabyte HyperDrive'M, (Over half of this time is spent in disk access, 
so the actual compile time is about 90 seconds.)" (The raw compile speed numbers are still accurate 
—the compiler actually compiles more than 22,000 lines due to included files.) 





page 3-7: 
The manual says "pull down the Source menu and select Run". It should read "pull down the 
Project menu and select Run". 


page 10-7: 
The line 
mode = "w+"; 
should be 


mode = “at”; 


page 13-1: 
The name of the Unix memory allocation functions library is storageu, not storageu.lib. 


page 13-14: 
In the calloc example, the line 3 lines from the bottom should read: 
if ( (newmonth = (date *) calloc(31, sizeof(date)) ) 


page 13-24: 
The function closeall() is called automatically on all program terminations that call the stdio 
file functions. ExitToShell from Macsbug will also call cl1oseall(). 


page 13-23: 
The sentence 


fclose () closes a file when given a file descriptor number. 
should be 
fclose () closes a file when given a file pointer. 


page 13-32: 
The £include statement should be 
#include "ctype.h" 


isascii(c) is TRUE if c lies in the range of 0 to 127 (Ox7f). 


iscntrl(c)isalso TRUE ifc == 127 (Ox7f). 
ispunct (c) is also TRUE if c == '@'orc == '^', 
isspace (c) is also TRUE if c == 0x3, the value of the Macintosh Enter key. 


Note that the actual .. ctype data table is in the file stddata_ctype.c which is part of the stdio 
library. You can add either (but not both) files to your project to get the table. 
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page 13-33: 


The line 
space . 178 
should be 
space 128 


page 13-39: 
Buffers do not have to be flushed before closing files. You may want to use fflush() after 
writing to a file or doing a printf to the printer. 


page 13-57: 
getchar() and fgetc(stdin) echo their output depending on the state of echo. See 
Set Echo() in the User's Manual. 


page 13-85: 
In the printf function example, the format specifier is given as "$03 d". It should read 
"$03d" (without a space between the 3 and the d). 


page 13-110: 
In the scanf description of right bracket (1), the last two paragraphs on the page are wrong. 
scanf does not support the "range of consecutive characters" feature described, nor does it allow a 
right bracket (] ) in the scanset. 


page 13-110: 
If scanf() is being used to input numbers of type float, short double, or double, the 
specifications should be $£, $h£, $1£, respectively. 


page 13-114: 
The functions set jmp and 1ong jmp and the variable jmpbuf are ascribed to the unix library. 
They are really in the library setjmp.lib. Include setjmp.h to get access to the definition of these 
items. In this release, set jmp and longjmp are also included in stdio, so don't include both 
setjmp.lib and stdio. 


page 13-123: 
At the end of this appendix is a replacement manual page. 


page 13-168: 
Using ungetc () to push back EOF has no effect on the stream. EOF is returned. 


page 13-169: 
The declaration should be 
int ungetch(c); 

int m 
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nage 14-27: 


— The declaration for Get ItemMark and Get ItemIcon should be 


void GetItemIcon (menu, 


MenuHandle menu; 
int item; 
int *iconNum; /* 


void GetItemMark (menu, 


MenuHandle menu; 
int item; 3 
int *markChar; / * 


NOT Byte *iconNum */ 


NOT char *markChar */ 


This change is due to the fact that, in Pascal, the Byte and Char types actually correspond to the C 
type int, unless a variable is explicitly packed in a record or an array. In the LightspeedC header 
file MacTypes.h, Byte is actually defined to be unsigned char, because Bytes are usually 


packed. 
page 14-45: 


The correct spelling is UnloadSeg (), not UnLoadSeg (). 
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Page 61 


get an argument from a string | stcarg 
(unix strings) 


SYNTAX #include <strings.h> 
int stcarg(s,b) 
char *s, *b; 


DESCRIPTION stcarg() scans the text string s until a character in the break string b is 
found or until it reaches the end of s. It returns the length of the sub- 
string prior to the break character. If no match was found, the length of s 
is returned. Anything in the string enclosed in single or double quotes 
will not match characters in the break string. A backslash in either string 
is treated as an escape character. 


EXAMPLES stcarg ("abcde", "12345") /* returns 5 - no match */ 
stcarg ("aabcd", "aeiou"™) /* returns 0 */ 
stcarg("aeiou", "aabcd") /* returns 0 */ 


RETURN VALUE the length of the sub-string prior to the break character. If no match was 
found, the length of s is returned. 


13-123 
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